home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / rtextu10.zip / MCOL.DOC < prev    next >
Text File  |  1993-05-06  |  10KB  |  212 lines
  1.  
  2.  
  3.                         #     #  #####                 
  4.                         ##   ## #     #   ####   #     
  5.                         # # # # #        #    #  #     
  6.                         #  #  # #        #    #  #     
  7.                         #     # #        #    #  #     
  8.                         #     # #     #  #    #  #     
  9.                         #     #  #####    ####   ######
  10.  
  11.  
  12.  
  13.  
  14. You can get part of the following documentation by invoking the program with
  15. the switches -v, -h, or -H . See README.TXT for more information.
  16.  
  17. -----------------------------------   -v   ------------------------------------
  18. MCOL v1.0 -- Arrange text in multiple columns
  19. Copr (c) 1992,1993 Richard Breuer. MCOL is freeware. No warranties.
  20.  
  21. This is MCOL/2 v1.0 - renamed to MCOL (from RUTILS 4).
  22.  
  23. Author: Richard Breuer
  24.         Brunssumstrasse 6
  25.         5100 Aachen
  26.         (after Jul 1, 1993: 52074 Aachen)
  27.         Germany
  28.         Europe
  29.  
  30. Phone:  +49/241/85605
  31. Fax:    +49/241/8021329
  32.  
  33. Email:  ricki@pool.informatik.rwth-aachen.de (Preferred!)
  34.  
  35. -----------------------------------   -h   ------------------------------------
  36. MCOL v1.0 -- Arrange text in multiple columns
  37. Copr (c) 1992,1993 Richard Breuer. MCOL is freeware. No warranties.
  38.  
  39. Usage:
  40.    MCOL [-c:f:hHl:s:tv*] infile.. [{>|>>} outfile]
  41.  
  42. Options (-c and -f are mutually exclusive):
  43.    -c<c>  Arrange text in c columns (default is c=2)
  44.    -f<f>  Define the line layout. See "Format" below for details
  45.    -h     Display this help screen
  46.    -H     Display another help screen with notes and examples
  47.    -l<l>  Set page length (default is l=66; l must be <= 128)
  48.    -s<s>  Set page separator string (default is s=!12, ie. ^L=form feed)
  49.    -t     Truncate lines, which are too long (default is: wrap lines)
  50.    -v     Display version info and information about the author
  51.    -*     Display internal information (for debugging purposes)
  52.  
  53. Format:
  54.    The -f<f> option gives you a powerful possibility to define the line layout.
  55.    You can specify text constant in s as well as ranges where the input text is
  56.    placed. Consider the call MCOL -f'@20 - @20', which defines two regions
  57.    of 20 characters each for the input text (the @ serves as a metacharacter)
  58.    which are separated with the three characters ' - '.
  59.  
  60. -----------------------------------   -H   ------------------------------------
  61. MCOL v1.0 -- Arrange text in multiple columns
  62. Copr (c) 1992,1993 Richard Breuer. MCOL is freeware. No warranties.
  63.  
  64. Notes:
  65.    MCOL reads from stdin if a filename is -. The output is always directed
  66.    to stdout. The line lengths are restricted to 255 characters. Longer lines
  67.    will be cut. The errorlevel is set to 1 if help has been displayed. It is
  68.    set to 255 in case of an error and 0 on normal completion. Output resulting
  69.    from multiple input files is appended to stdout. The processing order for
  70.    wildcards depends on the order of the directory entries. MCOL returns
  71.    nonsense for binary files.
  72.  
  73.    The standard format is computed as follows: the line width is set to 78. The
  74.    columns are separated by 2 blanks. The remaining space is equally used for
  75.    the column texts.
  76.  
  77. Examples:
  78.    MCOL LYRICS.TXT
  79.       Formats LYRICS.TXT in 2 columns. Long lines will be wrapped.
  80.    MCOL -f'#@80  @80' TEST.IN > TEST.OUT
  81.       Inserts a '#' at the beginning of every line of TEST.IN and writes the
  82.       result in two columns to TEST.OUT. Note that the resulting output line
  83.       length is 1+80+2+80=163 characters.
  84.  
  85. -------------------------------------------------------------------------------
  86. Additional information:
  87.    I wrote MCOL to help me formatting files containing lyrics. These files
  88.    are often less than 40 characters wide. I wanted to re-format them into
  89.    two columned text (if you have ever done this by hand, you know what
  90.    clumsy means :-) ). MCOL makes this task an easy one:
  91.  
  92.         MCOL input.fil > output.fil
  93.  
  94.    and you have a two-columned text file.
  95.  
  96.    There are several options to control MCOLs behaviour, ie. the number of
  97.    columns, page separators, and the powerful -f option (see above).
  98.  
  99.    Speaking of page separators. Since version 4 of RUTILS you can pass
  100.    arbitrary binary characters to the programs. This proves very useful for
  101.    MCOL, because you can eg. pass a header string to it which will appear
  102.    on top of every page but the first one:
  103.  
  104.         MCOL input.fil -s!12'This is a header string'!13!10 > output.fil
  105.  
  106.    where the meaning of the character codes is
  107.  
  108.         !12     form feed; tells the printer to eject the current page
  109.         !13     carriage return..
  110.         !10     ..line feed are DOS's way to terminate a line in a text file
  111.  
  112.    Analogously you can specify a footer string which will appear on the
  113.    bottom of each page but the last one:
  114.  
  115.         MCOL input.fil -s'This is a footer string'!12 > output.fil
  116.  
  117.    These examples also give you a good impression of the behaviour of the
  118.    command line parser I wrote.
  119.  
  120. Examples:
  121.    Let's consider the following input file FOO.DAT
  122.  
  123.         >I'm a little piece of code<
  124.         >Master Ricki did me wrote<
  125.         >This rhyme is English bad in style<
  126.         >and nothing but a testing file.<
  127.         >Although I might be just some shit<
  128.         >for testing MCOL I do fit.<
  129.         >                             Ricki<
  130.  
  131.    Here's the result of several MCOL calls with various parameters:
  132.  
  133.    MCOL FOO.DAT -l4
  134.    ----------------
  135.    >I'm a little piece of code              Although I might be just some shit<
  136.    >Master Ricki did me wrote               for testing MCOL I do fit.<
  137.    >This rhyme is English bad in style                                   Ricki<
  138.    >and nothing but a testing file.
  139.  
  140.    The page length was set to 4 to illustrate the multicolumn formatting
  141.    (otherwise everything would have been placed in one large column). We will
  142.    now introduce the -f option, which gives us a good possibility to illustrate
  143.    MCOLs features.
  144.  
  145.    The format of the argument of -f is an arbitrary text string. In this string
  146.    the characater @ plays the role of a meta character. If it is followed by a
  147.    number, eg. @40, this is interpreted as a position, where 40 characters of
  148.    the input text may be placed. The format defined here is applied to every
  149.    line of the input text. It's much easier to illustrate this with our example:
  150.  
  151.    MCOL -f'...   @15   ---   @15   ...' -l4 FOO.DAT
  152.    ------------------------------------------------
  153.    ...   I'm a little pi   ---   This rhyme is E   ...
  154.    ...   ece of code       ---   nglish bad in s   ...
  155.    ...   Master Ricki di   ---   tyle              ...
  156.    ...   d me wrote        ---   and nothing but   ...
  157.    ^L...    a testing file   ---   shit              ...
  158.    ...   .                 ---   for testing MCO   ...
  159.    ...   Although I migh   ---   L I do fit.       ...
  160.    ...   t be just some    ---                     ...
  161.    ^L...                 R   ---                     ...
  162.    ...   icki              ---                     ...
  163.  
  164.    The result is: two columns (because two @15 appear in the -f argument) with
  165.    a width of 15 characters each. The text lines which do not fit in one
  166.    column, are split and the rest is put in the next line. The text constants
  167.    "...   ", "   ---   ", and "   ..." are copied in each line. Again, we set
  168.    the page length to 4 lines. Therefore, the result consists of 3 pages which
  169.    are separated by ^L (default, because ^L is the form feed control code of
  170.    the most printers). You may change this separator to any other character or
  171.    string, eg.
  172.  
  173.    MCOL FOO.DAT -l3 -s'-- This is a different separator --'!13!10
  174.    --------------------------------------------------------------
  175.    I'm a little piece of code              This rhyme is English bad in style
  176.    Master Ricki did me wrote               and nothing but a testing file.
  177.    -- This is a different separator --
  178.    Although I might be just some shit                                   Ricki
  179.    for testing MCOL I do fit.
  180.  
  181.    In this case a whole string is used as sep